CListView Class

A list-view control is a window that displays a collection of items. List-view controls provide several ways to arrange and display items and are much more flexible than simple List Boxes. For example, additional information about each item can be displayed in columns to the right of the icon and label.

See: About List-View Controls

Include file: CListView.inc

AddColumn

Inserts a new column in a list-view control.

FUNCTION AddColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYREF wszText AS WSTRING, _
   BYVAL nWidth AS LONG, BYVAL nFormat AS LONG = LVCFMT_LEFT) AS LONG

Usage example

DIM wszText AS WSTRING * 260
FOR i AS LONG = 1 TO 5
   wszText = "Column " & STR(i)
   CListView.AddColumn(i, wszText, 50)
NEXT

AddItem

Inserts a new item in a list-view control.

FUNCTION AddItem (BYVAL hListView AS HWND, BYVAL iItem AS LONG, BYVAL iImage AS LONG, _
   BYREF wszText AS WSTRING) AS LONG

Return value

Returns the index of the new item if successful, or -1 otherwise.

AppendItem

Appends a new item in a list-view control.

FUNCTION AppendItem (BYVAL hListView AS HWND, BYVAL iImage AS LONG, BYVAL pwszText AS WSTRING PTR) AS LONG

Return value

Returns the index of the new item if successful, or -1 otherwise.

ApproximateViewRect

Calculates the approximate width and height required to display a given number of items.

FUNCTION ApproximateViewRect (BYVAL hListView AS HWND, BYVAL iWidth AS SHORT, _
   BYVAL iHeight AS SHORT, BYVAL iCount AS LONG) AS DWORD

Return value

Returns a DWORD value that holds the approximate width (in the LOWORD) and height (in the HIWORD) needed to display the items, in pixels.

Arrange

Arranges items in icon view.

FUNCTION Arrange (BYVAL hListView AS HWND, BYVAL code AS UINT) AS BOOLEAN

Return value

Returns TRUE if successful; otherwise, FALSE.

AutoSizeColumns

Automatically sizes all the columns of a listview

FUNCTION AutoSizeColumns (BYVAL hListView AS HWND) AS BOOLEAN

AutoSizeHeader

Automatically sizes all the columns of the header of a listview

FUNCTION AutoSizeHeader (BYVAL hListView AS HWND) AS BOOLEAN

CancelEditLabel

Cancels an item text editing operation.

FUNCTION AutoSizeHeader (BYVAL hListView AS HWND) AS BOOLEAN

Remarks

To use CancelEditLabel, specify Comctl32.dll version 6 in the manifest.

CreateDragImage

Creates a drag image list for the specified item.

FUNCTION CreateDragImage (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL lpptUpLeft AS POINT PTR) AS HIMAGELIST
FUNCTION CreateDragImage (BYVAL hListView AS HWND, BYVAL i AS LONG, BYREF tUpLeft AS POINT) AS HIMAGELIST
FUNCTION CreateDragImage (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL x AS LONG, BYVAL y AS LONG) AS HIMAGELIST

Return value

Returns the handle to the drag image list if successful, or NULL otherwise.

Remarks

Your application is responsible for destroying the image list when it is no longer needed.

DeleteAllItems

Removes all items from a list-view control.

FUNCTION DeleteAllItems (BYVAL hListView AS HWND) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

When a list-view control receives the LVM_DELETEALLITEMS message, it sends the LVN_DELETEALLITEMS notification code to its parent window.

DeleteColumn

Removes a column from a list-view control.

FUNCTION DeleteColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Deleting column zero of a list-view control is supported only in ComCtl32.dll version 6 and later. Version 5 also supports deleting column zero, but only after you use CCM_SETVERSION to set the version to 5 or later. In versions prior to version 5, if you must delete column zero, insert a zero length dummy column zero and delete column one and above.

DeleteItem

Removes an item from a list-view control.

FUNCTION DeleteItem (BYVAL hListView AS HWND, BYVAL i AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

EditLabel

Begins in-place editing of the specified list-view item’s text. The message implicitly selects and focuses the specified item.

FUNCTION EditLabel (BYVAL hListView AS HWND, BYVAL i AS LONG) AS HWND

Return value

Returns the handle to the edit control that is used to edit the item text if successful, or NULL otherwise.

Remarks

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can subclass the edit control, but you should not destroy it.

The control must have the focus before you send this message to the control. Focus can be set using the SetFocus function.

EnableGroupView

Enables or disables whether the items in a list-view control display as a group.

FUNCTION EnableGroupView (BYVAL hListView AS HWND, BYVAL fEnable AS BOOLEAN) AS LONG

Return value

Returns one of the following values:

Remarks

To use EnableGroupView, specify Comctl32.dll version 6 in the manifest.

EnsureVisible

Ensures that a list-view item is either entirely or partially visible, scrolling the list-view control if necessary.

FUNCTION EnsureVisible (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL fPartialOK AS BOOLEAN) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

FindItem

Searches for a list-view item with the specified characteristics.

FUNCTION FindItem (BYVAL hListView AS HWND, BYVAL iStart AS LONG, BYVAL pvfi AS LVFINDINFOW PTR) AS LONG
FUNCTION FindItem (BYVAL hListView AS HWND, BYVAL iStart AS LONG, BYREF vfi AS LVFINDINFOW) AS LONG

Return value

Returns the index of the item if successful, or -1 otherwise.

FindString

Searches for a list-view item with the specified text.

FUNCTION FindString (BYVAL hListView AS HWND, BYVAL pwszText AS WSTRING PTR) AS LONG

Return value

Returns the index of the item if successful, or -1 otherwise.

FitContent

Automatically sizes the specified column.

FUNCTION FitContent (BYVAL hListView AS HWND, BYVAL iCol AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

FitHeader

Automatically sizes the column to fit the header text. If you use this value with the last column, its width is set to fill the remaining width of the list-view control.

FUNCTION FitHeader (BYVAL hListView AS HWND, BYVAL iCol AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Assume that you have a 2-column list-view control with a width of 500 pixels. If the width of column zero is set to 200 pixels, and you send this message with iCol = 1 the second (and last) column will be 300 pixels wide.

GetBkColor

Gets the background color of a list-view control.

FUNCTION GetBkColor (BYVAL hListView AS HWND) AS COLORREF

Return value

Returns the background color of the list-view control.

GetBkImage

Gets the background image in a list-view control.

FUNCTION GetBkImage (BYVAL hListView AS HWND, BYVAL pvbki AS LVBKIMAGEW PTR) AS BOOLEAN
FUNCTION GetBkImage (BYVAL hListView AS HWND, BYREF vbki AS LVBKIMAGEW) AS BOOLEAN
FUNCTION GetBkImage (BYVAL hListView AS HWND) AS LVBKIMAGEW

Return value

Returns TRUE if successful, or FALSE otherwise.

GetCallbackMask

Gets the callback mask for a list-view control.

FUNCTION GetCallbackMask (BYVAL hListView AS HWND) AS UINT

Return value

Returns the callback mask.

GetCheckState

Determines if an item in a list-view control is selected. This should be used only for list-view controls that have the LVS_EX_CHECKBOXES style.

FUNCTION GetCheckState (BYVAL hListView AS HWND, BYVAL i AS LONG) AS UINT

Return value

Returns nonzero if the given item is selected, or zero otherwise. If this method is applied to a list-view control that does not have check boxes enabled, the return value is not reliable.

GetColumn

Gets the attributes of a list-view control’s column.

FUNCTION GetColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYVAL pcol AS LVCOLUMNW PTR) AS BOOLEAN
FUNCTION GetColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYREF col AS LVCOLUMNW) AS BOOLEAN
FUNCTION GetColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG) AS LVCOLUMNW

Return value

Returns TRUE if successful, or FALSE otherwise.

GetColumnCount

Gets the number of columns of a listview.

FUNCTION GetColumnCount (BYVAL hListView AS HWND) AS LONG

Return value

Returns the number of items if successful, or -1 otherwise.

GetColumnOrder

Gets the order of the specified column of the listview’s header control.

FUNCTION GetColumnOrder (BYVAL hListView AS HWND, BYVAL iCol AS LONG) AS LONG

Return value

The order in which the item appears within the header control, from left to right. That is, the value for the far left item is 0. The value for the next item to the right is 1, and so on.

GetColumnText

Gets the text of a list-view control’s column.

FUNCTION GetColumnText (BYVAL hListView AS HWND, BYVAL iCol AS LONG, _
   BYVAL cchTextMax AS LONG = MAX_PATH + 1) AS DWSTRING

Return value

The column name.

GetColumnOrderArray

Gets the current left-to-right order of columns in a list-view control.

FUNCTION GetColumnOrderArray (BYVAL hListView AS HWND, BYVAL iCount AS LONG, BYVAL lpiArray AS LONG PTR) AS LONG

Return value

If successful, returns nonzero and the buffer at lpiArray receives the column index of each column in the control in the order they appear from left to right. Otherwise, the return value is zero.

GetColumnWidth

Gets the width of a column in report or list view.

FUNCTION GetColumnWidth (BYVAL hListView AS HWND, BYVAL iCol AS LONG) AS LONG

Return value

Returns the column width if successful, or zero otherwise. If this method is used on a list-view control with the LVS_REPORT style and the specified column does not exist, the return value is undefined.

GetCountPerPage

Calculates the number of items that can fit vertically in the visible area of a list-view control when in list or report view. Only fully visible items are counted.

FUNCTION GetCountPerPage (BYVAL hListView AS HWND) AS LONG

Return value

Returns the number of fully visible items if successful. If the current view is icon or small icon view, the return value is the total number of items in the list-view control.

GetEditControl

Gets the handle to the edit control being used to edit a list-view item’s text.

FUNCTION GetEditControl (BYVAL hListView AS HWND) AS HWND

Return value

Returns the handle to the edit control if successful, or NULL otherwise.

Remarks

When label editing begins, an edit control is created, positioned, and initialized. Before it is displayed, the list-view control sends its parent window an LVN_BEGINLABELEDIT notification code.

To customize label editing, implement a handler for LVN_BEGINLABELEDIT and have it use GetEditControl to send an LVM_GETEDITCONTROL message to the list-view control. If a label is being edited, the return value will be a handle to the edit control. Use this handle to customize the edit control by sending the usual EM_XXX messages.

When the user completes or cancels editing, the edit control is destroyed and the handle is no longer valid. You can subclass the edit control, but you should not destroy it. To cancel editing, you can send the list-view control a WM_CANCELMODE message.

The list-view item being edited is the currently focused item—that is, the item in the focused state. To find an item based on its state, use the LVM_GETNEXTITEM message.

GetEmptyText

Gets the text meant for display when the list-view control appears empty.

FUNCTION GetEmptyText (BYVAL hListView AS HWND, BYVAL pwszText AS WSTRING PTR, BYVAL cchText AS DWORD) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

GetExtendedListViewStyle

Gets the extended styles that are currently in use for a given list-view control.

FUNCTION GetExtendedListViewStyle (BYVAL hListView AS HWND) AS DWORD

Return value

Returns a DWORD value that represents the styles currently in use for a given list-view control. This can be a combination of extended styles.

GetFocusedGroup

Gets the group that has the focus.

FUNCTION GetFocusedGroup (BYVAL hListView AS HWND) AS LONG

Return value

Returns the index of the group with state of LVGS_FOCUSED, or -1 if there is no group with state of LVGS_FOCUSED.

GetFocusedItem

Gets the item that has the focus, which may or may not be selected.

FUNCTION GetFocusedItem (BYVAL hListView AS HWND) AS LONG

Return value

Returns the index of the next item if successful, or -1 otherwise.

GetFooterInfo

Gets information on the footer of a specified list-view control.

FUNCTION GetFooterInfo (BYVAL hListView AS HWND, BYVAL pvfi AS LVFOOTERINFO PTR) AS BOOLEAN
FUNCTION GetFooterInfo (BYVAL hListView AS HWND, BYREF vfi AS LVFOOTERINFO) AS BOOLEAN
FUNCTION GetFooterInfo (BYVAL hListView AS HWND) AS LVFOOTERINFO

Return value

Returns TRUE.

GetFooterItem

Gets information on a footer item for a specified list-view control.

FUNCTION GetFooterItem (BYVAL hListView AS HWND, BYVAL iItem AS LONG, BYVAL pfi AS LVFOOTERITEM PTR) AS BOOLEAN
FUNCTION GetFooterItem (BYVAL hListView AS HWND, BYVAL iItem AS LONG, BYREF fi AS LVFOOTERITEM) AS BOOLEAN
FUNCTION GetFooterItem (BYVAL hListView AS HWND, BYVAL iItem AS UINT) AS LVFOOTERITEM

Return value

Returns TRUE if successful, or FALSE otherwise.

GetFooterItemRect

Gets the coordinates of a footer for a specified item in a list-view control.

FUNCTION GetFooterItemRect (BYVAL hListView AS HWND, BYVAL iItem AS UINT, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetFooterItemRect (BYVAL hListView AS HWND, BYVAL iItem AS UINT, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetFooterItemRect (BYVAL hListView AS HWND, BYVAL iItem AS UINT) AS RECT

Return value

Returns TRUE if successful, or FALSE otherwise.

GetFooterRect

Gets the coordinates of the footer for a specified list-view control.

FUNCTION GetFooterRect (BYVAL hListView AS HWND, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetFooterRect (BYVAL hListView AS HWND, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetFooterRect (BYVAL hListView AS HWND) AS RECT

Return value

Returns TRUE if successful, or FALSE otherwise.

GetGroupCount

Gets the number of groups.

FUNCTION GetGroupCount (BYVAL hListView AS HWND) AS LONG

Return value

Returns the number of groups if successful, or -1 otherwise.

Remarks

To use GetGroupCount, specify Comctl32.dll version 6 in the manifest.

GetGroupHeaderImageList

Gets the group header image list that has been set for an existing list-view control.

FUNCTION GetGroupHeaderImageList (BYVAL hListView AS HWND) AS HIMAGELIST

Return value

Returns the handle to the group header image list if successful, or NULL otherwise.

Remarks

To specify an image list another way, such as, by large icons, small icons, or state images, send the LVM_GETIMAGELIST message explicitly.

GetGroupInfo

Gets group information.

FUNCTION GetGroupInfo (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYVAL pgrp AS LVGROUP PTR) AS LONG
FUNCTION GetGroupInfo (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYREF grp AS LVGROUP) AS LONG

Return value

Returns the ID of the group if successful, or -1 otherwise.

Remarks

Before attempting to retrieve the header for a group, first ensure that the group does not have the LBGS_NOHEADER style.

To use GetGroupInfo, specify Comctl32.dll version 6 in the manifest.

GetGroupInfoByIndex

Gets information on a specified group

FUNCTION GetGroupInfoByIndex (BYVAL hListView AS HWND, BYVAL iIndex AS LONG, BYREF pgrp AS LVGROUP PTR) AS BOOLEAN
FUNCTION GetGroupInfoByIndex (BYVAL hListView AS HWND, BYVAL iIndex AS LONG, BYREF grp AS LVGROUP) AS BOOLEAN

Return value

Returns the ID of the group if successful, or -1 otherwise.

Remarks

Before attempting to retrieve the header for a group, first ensure that the group does not have the LBGS_NOHEADER style.

To use GetGroupInfo, specify Comctl32.dll version 6 in the manifest.

GetGroupMetrics

Gets information about the display of groups.

SUB GetGroupMetrics (BYVAL hListView AS HWND, BYVAL pGroupMetrics AS LVGROUPMETRICS PTR)
SUB GetGroupMetrics (BYVAL hListView AS HWND, BYREF GroupMetrics AS LVGROUPMETRICS)

Remarks

To use GetGroupMetrics, specify Comctl32.dll version 6 in the manifest.

GetGroupRect

Gets the rectangle for a specified group.

FUNCTION GetGroupRect (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYVAL nType AS LONG, _
   BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetGroupRect (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYVAL nType AS LONG, _
   BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetGroupRect (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYVAL nType AS LONG) AS RECT

Rectangle type:

Remarks

Returns TRUE if successful, or FALSE otherwise.

GetGroupState

Gets the state for a specified group.

FUNCTION GetGroupState (BYVAL hListView AS HWND, BYVAL dwGroupId AS UINT, BYVAL dwMask AS UINT) AS UINT

Remarks

Returns the combination of state values that are set. For example, if dwMask is LVGS_COLLAPSED and the value returned is zero, the LVGS_COLLAPSED state is not set. Zero is returned if the group is not found.

GetHeader

Gets the handle to the header control used by a list-view control.

FUNCTION GetHeader (BYVAL hListView AS HWND) AS HWND

Remarks

Returns the handle to the header control.

GetHeaderText

Gets the text of the specified column of the header of a listview control.

FUNCTION GetHeaderText (BYVAL hListView AS HWND, BYVAL iCol AS LONG, _
   BYVAL cchTextMax AS LONG = MAX_PATH + 1) AS DWSTRING

Remarks

Returns the retrieved text.

GetHotCursor

Gets the HCURSOR used when the pointer is over an item while hot tracking is enabled.

FUNCTION GetHotCursor (BYVAL hListView AS HWND) AS HCURSOR

Return value

Returns an HCURSOR value that is the handle to the cursor that the list-view control uses when hot tracking is enabled.

Remarks

A list-view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

GetHotItem

Gets the index of the hot item.

FUNCTION GetHotItem (BYVAL hListView AS HWND) AS LONG

Return value

Returns the index of the item that is currently hot.

GetHoverTime

Gets the amount of time that the mouse cursor must hover over an item before it is selected.

FUNCTION GetHoverTime (BYVAL hListView AS HWND) AS DWORD

Return value

Returns the amount of time, in milliseconds, that the mouse cursor must hover over an item before it is selected. If the return value is (DWORD)-1, then the hover time is the default hover time.

Remarks

The hover time only affects list-view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list-view style.

GetImageList

Gets the handle to an image list used for drawing list-view items.

FUNCTION GetImageList (BYVAL hListView AS HWND, BYVAL iImageList AS LONG) AS HIMAGELIST

Return value

Returns the handle to the specified image list if successful, or NULL otherwise.

GetInsertMark

Gets the position of the insertion point.

FUNCTION GetInsertMark (BYVAL hListView AS HWND, BYVAL pvim AS LVINSERTMARK PTR) AS BOOLEAN
FUNCTION GetInsertMark (BYVAL hListView AS HWND, BYREF vim AS LVINSERTMARK) AS BOOLEAN
FUNCTION GetInsertMark (BYVAL hListView AS HWND) AS LVINSERTMARK

Return value

Returns TRUE if successful, or FALSE otherwise. Returns FALSE if the size in the cbSize member of the LVINSERTMARK structure does not equal the actual size of the structure.

Remarks

To use this method, you must provide a manifest specifying Comclt32.dll version 6.0.

GetInsertMarkColor

Gets the color of the insertion point.

FUNCTION GetInsertMarkColor (BYVAL hListView AS HWND) AS COLORREF

Return value

Returns a COLORREF value that contains the color of the insertion point.

Remarks

To use GetInsertMarkColor, specify Comctl32.dll version 6 in the manifest

GetInsertMarkRect

Gets the rectangle that bounds the insertion point.

FUNCTION GetInsertMarkRect (BYVAL hListView AS HWND, BYVAL prc AS RECT PTR) AS LONG
FUNCTION GetInsertMarkRect (BYVAL hListView AS HWND, BYREF prc AS RECT) AS LONG
FUNCTION GetInsertMarkRect (BYVAL hListView AS HWND) AS RECT

Return value

Returns one of the following values.

Remarks

To use GetInsertMarkRect, specify Comctl32.dll version 6 in the manifest

GetISearchString

Gets the incremental search string of a list-view control.

FUNCTION GetISearchString (BYVAL hListView AS HWND) AS DWSTRING

Return value

Returns the incremental search string.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A time-out period is associated with each character that the user types. If the time-out period elapses before the user types another character, the incremental search string is reset.

GetISearchStringLen

Gets the length of the incremental search string of a list-view control.

FUNCTION GetISearchStringLen (BYVAL hListView AS HWND) AS LONG

Return value

Returns the length of the incremental search string.

Remarks

The incremental search string is the character sequence that the user types while the list view has the input focus. Each time the user types a character, the system appends the character to the search string and then searches for a matching item. If the system finds a match, it selects the item and, if necessary, scrolls it into view.

A time-out period is associated with each character that the user types. If the time-out period elapses before the user types another character, the incremental search string is reset.

GetItem

Gets some or all of a list-view item’s attributes.

FUNCTION GetItem (BYVAL hListView AS HWND, BYVAL pitem AS LVITEMW PTR) AS BOOLEAN
FUNCTION GetItem (BYVAL hListView AS HWND, BYREF item AS LVITEMW) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the LVM_GETITEM message is sent, the iItem and iSubItem members identify the item or subitem to retrieve information about and the mask member specifies which attributes to retrieve. For a list of possible values, see the description of the LVITEM structure.

If the LVIF_TEXT flag is set in the mask member of the LVITEMW structure, the pszText member must point to a valid buffer and the cchTextMax member must be set to the number of characters in that buffer. Applications should not assume that the text will necessarily be placed in the specified buffer. The control may instead change the pszText member of the structure to point to the new text rather than place it in the buffer.

If the mask member specifies the LVIF_STATE value, the stateMask member must specify the item state bits to retrieve. On output, the state member contains the values of the specified state bits.

GetItemCount

Gets the number of items in a list-view control.

FUNCTION GetItemCount (BYVAL hListView AS HWND) AS LONG

Return value

Returns the number of items.

GetItemIndexRect

Gets the bounding rectangle for all or part of a subitem in the current view of a specified list-view control.

FUNCTION GetItemIndexRect (BYVAL hListView AS HWND, BYVAL pvii AS LVITEMINDEX PTR, _
   BYVAL iSubItem AS LONG, BYVAL code AS LONG, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetItemIndexRect (BYVAL hListView AS HWND, BYREF lvii AS LVITEMINDEX, _
   BYVAL iSubItem AS LONG, BYVAL code AS LONG, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetItemIndexRect (BYVAL hListView AS HWND, BYREF vii AS LVITEMINDEX, _
   BYVAL iSubItem AS LONG, BYVAL code AS LONG) AS RECT

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

If iSubItem is zero, this method returns the coordinates of the rectangle to the item pointed to by plvii. The value LVIR_SELECTBOUNDS for the parameter code is not supported.

GetItemPosition

Gets the position of a list-view item.

FUNCTION GetItemPosition (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL ppt AS POINT PTR) AS BOOLEAN
FUNCTION GetItemPosition (BYVAL hListView AS HWND, BYVAL i AS LONG, BYREF pt AS POINT) AS BOOLEAN
FUNCTION GetItemPosition (BYVAL hListView AS HWND, BYVAL i AS LONG) AS POINT

Return value

Returns TRUE if successful, or FALSE otherwise.

GetItemRect

Gets the bounding rectangle for all or part of an item in the current view.

FUNCTION GetItemRect (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetItemRect (BYVAL hListView AS HWND, BYVAL i AS LONG, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetItemRect (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL code AS LONG) AS RECT

Return value

Returns TRUE if successful, or FALSE otherwise.

GetItemSpacing

Determines the spacing between items in a list-view control.

FUNCTION GetItemSpacing (BYVAL hListView AS HWND, BYVAL fSmall AS BOOLEAN) AS DWORD

Return value

Returns the amount of spacing between items. The horizontal spacing is contained in the LOWORD and the vertical spacing is contained in the HIWORD.

GetItemHorizontalSpacing

Determines the horizomtal spacing between items in a list-view control.

FUNCTION GetItemHorizontalSpacing (BYVAL hListView AS HWND, BYVAL fSmall AS BOOLEAN) AS DWORD

Return value

Returns the horizontal spacing between items.

GetItemVerticalSpacing

Determines the vertical spacing between items in a list-view control.

FUNCTION GetItemVerticalSpacing (BYVAL hListView AS HWND, BYVAL fSmall AS BOOLEAN) AS DWORD

Return value

Returns the vertical spacing between items.

GetItemState

Gets the state of a list-view item.

FUNCTION GetItemState (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL mask AS LONG) AS UINT

Return value

Returns the current state for the specified item. The only valid bits in the return value are those that correspond to the bits set in the mask parameter.

Remarks

An item’s state information includes a set of bit flags as well as image list indexes that indicate the item’s state image and overlay image.

GetItemText

Gets the text of a list-view item or subitem.

SUB GetItemText (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL iSubItem AS LONG, _
   BYVAL pwszText AS WSTRING PTR, BYVAL cchTextMax AS LONG  = MAX_PATH + 1)
FUNCTION GetText (BYVAL hListView AS HWND, BYVAL item AS LONG, BYVAL iSubItem AS LONG, _
   BYVAL cchTextMax AS LONG = MAX_PATH + 1) AS DWSTRING

GetNextItem

Searches for a list-view item that has the specified properties and bears the specified relationship to a specified item.

FUNCTION GetNextItem (BYVAL hListView AS HWND, BYVAL iStart AS LONG, BYVAL flags AS UINT) AS LONG

Return value

Returns the index of the next item if successful, or -1 otherwise.

GetNextItemIndex

Gets the index of the item in a particular list-view control that has the specified properties and relationship to another specific item.

FUNCTION GetNextItemIndex (BYVAL hListView AS HWND, BYVAL plvii AS LVITEMINDEX PTR, BYVAL flags AS ..LPARAM) AS LONG
FUNCTION GetNextItemIndex (BYVAL hListView AS HWND, BYREF lvii AS LVITEMINDEX, BYVAL flags AS ..LPARAM) AS LONG

If an item does not have all of the specified state flags set, the search continues with the next item.

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

Note that the following flags, for use only with Windows Vista, are mutually exclusive of any other flags in use: LVNI_PREVIOUS, LVNI_VISIBLEONLY, LVNI_SAMEGROUPONLY, LVNI_VISIBLEORDER, LVNI_DIRECTIONMASK, and LVNI_STATEMASK.

GetNumberOfWorkAreas

Gets the number of working areas in a list-view control.

FUNCTION GetNumberOfWorkAreas (BYVAL hListView AS HWND) AS DWORD

Return value

The number of working areas in the list-view control.

GetOrderArray

Gets the current left-to-right order of items in the header of a listview control.

FUNCTION GetOrderArray (BYVAL hListView AS HWND, BYVAL iCount AS DWORD, BYVAL lpi AS LONG PTR) AS LONG

Return value

Returns nonzero if successful, and the buffer at lpi receives the item number for each item in the header control in the order in which they appear from left to right. Otherwise, the message returns zero.

Remarks

The number of elements in lpi is specified in iCount and must be equal to the number of items in the control. For example, the following code fragment will reserve enough memory to hold the index values.

GetOrigin

Gets the current view origin for a list-view control.

FUNCTION GetOrigin (BYVAL hListView AS HWND, BYVAL pptOrg AS POINT PTR) AS BOOLEAN
FUNCTION GetOrigin (BYVAL hListView AS HWND, BYREF ptOrg AS POINT) AS BOOLEAN
FUNCTION GetOrigin (BYVAL hListView AS HWND) AS POINT

Return value

Returns TRUE if successful, or FALSE if the current view is list or report view.

GetOutlineColor

Gets the color of the border of a list-view control if the LVS_EX_BORDERSELECT extended window style is set.

FUNCTION GetOutlineColor (BYVAL hListView AS HWND) AS COLORREF

Return value

Returns a COLORREF structure that contains the color of the border of a list-view control.

Remarks

To use GetOutlineColor, specify Comctl32.dll version 6 in the manifest.

GetSelectedColumn

Gets an integer that specifies the selected column.

FUNCTION GetSelectedColumn (BYVAL hListView AS HWND) AS UINT

Return value

Returns a UINT that specifies the selected column.

Remarks

To use GetSelectedColumn, specify Comctl32.dll version 6 in the manifest.

GetSelectedCount

Determines the number of selected items in a list-view control.

FUNCTION GetSelectedCount (BYVAL hListView AS HWND) AS UINT

Return value

Returns the number of selected items.

GetSelection

Returns the zero-based index of the currently selected item.

FUNCTION GetSelection (BYVAL hListView AS HWND) AS LONG

Return value

THe zero-based index of the currently selected item.

GetSelectionMark

Gets the selection mark from a list-view control.

FUNCTION GetSelectionMark (BYVAL hListView AS HWND) AS LONG

Return value

Returns the zero-based selection mark, or -1 if there is no selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts.

GetStringWidth

Determines the width of a specified string using the specified list-view control’s current font.

FUNCTION GetStringWidth (BYVAL hListView AS HWND, BYREF wszText AS WSTRING) AS LONG

Return value

Returns the string width if successful, or zero otherwise.

Remarks

The GetStringWidth method returns the exact width, in pixels, of the specified string. If you use the returned string width as the column width in a call to the SetColumnWidth metod, the string will be truncated. To retrieve the column width that can contain the string without truncating it, you must add padding to the returned string width.

GetSubItemRect

Gets information about the rectangle that surrounds a subitem in a list-view control. This method is intended to be used only on list-view controls that use the LVS_REPORT style.

FUNCTION GetSubItemRect (BYVAL hListView AS HWND, BYVAL iItem AS LONG, BYVAL iSubItem AS LONG, _
   BYVAL nCode AS LONG, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetSubItemRect (BYVAL hListView AS HWND, BYVAL iItem AS LONG, BYVAL iSubItem AS LONG, _
   BYVAL nCode AS LONG, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetSubItemRect (BYVAL hListView AS HWND, BYVAL iItem AS LONG, BYVAL iSubItem AS LONG, _
   BYVAL nCode AS LONG) AS RECT

Return value

Returns TRUE if successful, or FALSE otherwise.

GetTextBkColor

Gets the text background color of a list-view control.

FUNCTION GetTextBkColor (BYVAL hListView AS HWND) AS COLORREF

Return value

Returns the background color of the text.

GetTextColor

Gets the text color of a list-view control.

FUNCTION GetTextColor (BYVAL hListView AS HWND) AS COLORREF

Return value

Returns the text color.

GetTileInfo

Gets information about a tile in a list-view control.

SUB GetTileInfo (BYVAL hListView AS HWND, BYVAL pti AS LVTILEINFO PTR)
SUB GetTileInfo (BYVAL hListView AS HWND, BYREF ti AS LVTILEINFO)
FUNCTION GetTileInfo (BYVAL hListView AS HWND) AS LVTILEINFO

Remarks

To use GetTileInfo, specify Comctl32.dll version 6 in the manifest.

GetTileViewInfo

Gets information about a list-view control in tile view.

SUB GetTileViewInfo (BYVAL hListView AS HWND, BYVAL ptvi AS LVTILEVIEWINFO PTR)
SUB GetTileViewInfo (BYVAL hListView AS HWND, BYREF tvi AS LVTILEVIEWINFO)
FUNCTION GetTileViewInfo (BYVAL hListView AS HWND) AS LVTILEVIEWINFO

Remarks

To use GetTileViewInfo, specify Comctl32.dll version 6 in the manifest.

GetToolTips

Gets the tooltip control that the list-view control uses to display tooltips.

FUNCTION GetToolTips (BYVAL hListView AS HWND) AS HWND

Return value

Returns the handle to the tooltip control.

GetTooltipsFont

Retrieves the font used by the ToolTip control that the list-view control uses to display tooltips.

FUNCTION GetTooltipsFont (BYVAL hListView AS HWND) AS HFONT

Return value

The return value is a handle to the font used by the control, or NULL if the control is using the system font.

GetTopIndex

Gets the index of the topmost visible item when in list or report view.

FUNCTION GetTopIndex (BYVAL hListView AS HWND) AS LONG

Return value

Returns the index of the item if successful, or zero if the list-view control is in icon or small icon view.

GetView

Gets the current view of a list-view control.

FUNCTION GetView (BYVAL hListView AS HWND) AS DWORD

Return value

Returns a DWORD that specifies the current view.

Remarks

To use GetView, specify Comctl32.dll version 6 in the manifest.

GetViewRect

Gets the bounding rectangle of all items in the list-view control. The list view must be in icon or small icon view.

FUNCTION GetViewRect (BYVAL hListView AS HWND, BYVAL prc AS RECT PTR) AS BOOLEAN
FUNCTION GetViewRect (BYVAL hListView AS HWND, BYREF rc AS RECT) AS BOOLEAN
FUNCTION GetViewRect (BYVAL hListView AS HWND) AS RECT

Return value

Returns TRUE if successful, or FALSE otherwise.

GetWorkAreas

Gets the working areas from a list-view control.

SUB GetWorkAreas (BYVAL hListView AS HWND, BYVAL nWorkAreas AS LONG, BYVAL prc AS RECT PTR)
SUB GetWorkAreas (BYVAL hListView AS HWND, BYVAL nWorkAreas AS LONG, BYREF rc AS RECT)
FUNCION GetWorkAreas (BYVAL hListView AS HWND, BYVAL nWorkAreas AS LONG) AS RECT

HasGroup

Determines whether the list-view control has a specified group.

FUNCION HasGroup (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG) AS BOOLEAN

Return value

Returns TRUE if the list-view control has the specified group, or FALSE otherwise.

Remarks

To use ListView_HasGroup, specify Comctl32.dll version 6 in the manifest

HitTest

Determines which list-view item, if any, is at a specified position.

FUNCION HitTest (BYVAL hListView AS HWND, BYVAL pinfo AS LVHITTESTINFO PTR) AS LONG
FUNCION HitTest (BYVAL hListView AS HWND, BYREF info AS LVHITTESTINFO) AS LONG
FUNCION HitTest (BYVAL hListView AS HWND) AS LVHITTESTINFO

Return value

Returns the index of the item at the specified position, if any, or -1 otherwise.

HitTestEx

Determines which list-view item, if any, is at a specified position.

FUNCION HitTestEx (BYVAL hListView AS HWND, BYREF pinfo AS LVHITTESTINFO PTR) AS LONG
FUNCION HitTestEx (BYVAL hListView AS HWND, BYREF info AS LVHITTESTINFO) AS LONG
FUNCION HitTestEx (BYVAL hListView AS HWND) AS LVHITTESTINFO

Return value

Returns the index of the item at the specified position, if any, or -1 otherwise.

Remarks

This method passes -1 as the wParam of the message, specifying that the iGroup and iSubItem members of pinfo are retrieved.

InsertColumn

Inserts a new column in a list-view control.

FUNCTION InsertColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYVAL pcol AS LVCOLUMN PTR) AS LONG
FUNCTION InsertColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYREF col AS LVCOLUMN) AS LONG

Return value

Returns the index of the new column if successful, or -1 otherwise.

Remarks

Columns are visible only in report (details) view.

InsertGroup

Inserts a group into a list-view control.

FUNCTION InsertGroup (BYVAL hListView AS HWND, BYVAL index AS LONG, BYVAL pgrp AS LVGROUP PTR) AS LONG
FUNCTION InsertGroup (BYVAL hListView AS HWND, BYVAL index AS LONG, BYREF grp AS LVGROUP) AS LONG

Return value

Returns the index of the item that the group was added to, or -1 if the operation failed.

Remarks

To turn on group mode, call LVM_ENABLEGROUPVIEW or EnableGroupView.

To use InsertGroup, specify Comctl32.dll version 6 in the manifest.

InsertGroupSorted

Inserts a group into an ordered list of groups.

SUB InsertGroupSorted (BYVAL hListView AS HWND, BYVAL pstructInsert AS LVINSERTGROUPSORTED PTR)
SUB InsertGroupSorted (BYVAL hListView AS HWND, BYREF structInsert AS LVINSERTGROUPSORTED)

Return value

Returns the index of the item that the group was added to, or -1 if the operation failed.

Remarks

To use InsertGroupSorted, specify Comctl32.dll version 6 in the manifest.

InsertItem

Inserts a new item in a list-view control.

FUNCTION InsertItem (BYVAL hListView AS HWND, BYVAL pitem AS LVITEMW PTR) AS LONG
FUNCTION InsertItem (BYVAL hListView AS HWND, BYREF item AS LVITEMW) AS LONG

Return value

Returns the index of the new item if successful, or -1 otherwise.

Remarks

You cannot use InsertItem or LVM_INSERTITEM to insert subitems. The iSubItem member of the LVITEMW structure must be zero. See LVM_SETITEM for information on setting subitems.

If a list-view control has the LVS_EX_CHECKBOXES style set, any value placed in bits 12 through 15 of the state member of the LVITEMW structure will be ignored. When an item is added with this style set, it will always be set to the unchecked state.

If a list-view control has either the LVS_SORTASCENDING or LVS_SORTDESCENDING window style, an LVM_INSERTITEM message will fail if you try to insert an item that has LPSTR_TEXTCALLBACK as the pszText member of its LVITEMW structure.

The InsertItem method will insert the new item in the proper position in the sort order if the following conditions hold:

• You are using one of the LVS_SORTXXX styles.
• You are not using the LVS_OWNERDRAW style.
• The pszText member of the structure pointed to by pitem is not set to LPSTR_TEXTCALLBACK.

InsertMarkHitTest

Retrieves the insertion point closest to a specified point.

FUNCTION InsertMarkHitTest (BYVAL hListView AS HWND, BYVAL ppt AS POINT PTR, _
   BYVAL pvim AS LVINSERTMARK PTR) AS BOOLEAN
FUNCTION InsertMarkHitTest (BYVAL hListView AS HWND, BYREF pt AS POINT, _
   BYREF vim AS LVINSERTMARK) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

To use InsertMarkHitTest, specify Comctl32.dll version 6 in the manifest.

IsGroupViewEnabled

Checks whether the list-view control has group view enabled.

FUNCTION IsGroupViewEnabled (BYVAL hListView AS HWND) AS BOOLEAN

Return value

Returns TRUE if group view is enabled, or FALSE otherwise.

Remarks

To use IsGroupViewEnabled, specify Comctl32.dll version 6 in the manifest.

IsItemVisible

Indicates whether an item in the list-view control is visible.

FUNCTION IsItemVisible (BYVAL hListView AS HWND, BYVAL index AS UINT) AS BOOLEAN

Return value

Returns TRUE if group view is enabled, or FALSE otherwise.

MakeHeaderFlat

Removes the HDS_BUTTONS style from the header control to give it a flat appearance.

SUB MakeHeaderFlat (BYVAL hListView AS HWND)

MapIDToIndex

Maps the ID of an item to an index.

FUNCTION MapIDToIndex (BYVAL hListView AS HWND, BYVAL id AS UINT) AS UINT

Return value

Returns the most current index.

Remarks

List-view controls internally track items by index. This can present problems because indexes can change during the control’s existence.

You can use this method to tag an item with an ID when you create the item. You use this ID to guarantee uniqueness during the existence of the list-view control.

To uniquely identify an item, take the index that returns from a call such IComponent.GetDisplayInfo and call LVM_MAPINDEXTOID. The return value is a unique ID.

If you need to know the index of an item after creating an ID, call LVM_MAPIDTOINDEX with the unique ID and it returns the most current index.

Note: In a multithreaded environment, you can only be sure the correct index is returned on the thread that hosts the list-view control, not on background threads.

To use apIDToIndex, specify Comctl32.dll version 6 in the manifest.

MapIndexToID

Maps the index of an item to a unique ID.

FUNCTION MapIndexToID (BYVAL hListView AS HWND, BYVAL index AS UINT) AS UINT

Return value

Returns a unique ID.

Remarks

List-view controls internally track items by index. This can present problems because indexes can change during the control’s existence.

You can use this method to tag an item with an ID when you create the item. You use this ID to guarantee uniqueness during the existence of the list-view control.

To uniquely identify an item, take the index that is returned from a call such IComponent.GetDisplayInfo and call LVM_MAPINDEXTOID. The return value is a unique ID.

Note: In a multithreaded environment, you can only be sure the correct index is returned on the thread that hosts the list-view control, not on background threads.

To use MapIndexToID, specify Comctl32.dll version 6 in the manifest.

ModifyHeaderFont

Modifies the font used by the listview header.

FUNCTION ModifyHeaderFont (BYVAL hListView AS HWND, BYREF wszFaceName AS WSTRING, _
   BYVAL lPointSize AS LONG, BYVAL lWeight AS LONG, BYVAL bItalic AS BYTE, BYVAL bUnderline AS BYTE, _
   BYVAL bStrikeOut AS BYTE, BYVAL bCharSet AS BYTE) AS HFONT              

Return value

The handle of the new font. The returned font must be destroyed with DeleteObject when no longer needed to prevent memory leaks.

RedrawItems

Forces a list-view control to redraw a range of items.

FUNCTION RedrawItems (BYVAL hListView AS HWND, BYVAL iFirst AS LONG, BYVAL iLast AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

The specified items are not actually redrawn until the list-view window receives a WM_PAINT message to repaint. To repaint immediately, call the UpdateWindow function after using this method.

RemoveAllGroups

Removes all groups from a list-view control.

SUB RemoveAllGroups (BYVAL hListView AS HWND)

Remarks

To use RemoveAllGroups, specify Comctl32.dll version 6 in the manifest.

RemoveDarkMode

Removes the listview dark mode.

FUNCTION RemoveDarkMode (BYVAL hListView AS HWND) AS HRESULT

RemoveGroup

Removes a group from a list-view control.

FUNCTION RemoveGroup (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG) AS LONG

Return Values

Returns the index of the group if successful, or -1 otherwise.

Scroll

Scrolls the content of a list-view control.

FUNCTION Scroll (BYVAL hListView AS HWND, BYVAL dx AS LONG, BYVAL dy AS LONG) AS BOOLEAN

Return Values

Returns TRUE if successful, or FALSE otherwise.

Remarks

When the list-view control is in report view, the control can only be scrolled vertically in whole line increments. Therefore, the dy parameter will be rounded to the nearest number of pixels that form a whole line increment. For example, if the height of a line is 16 pixels and 8 is passed for dy, the list will be scrolled by 16 pixels (1 line). If 7 is passed for dy, the list will be scrolled 0 pixels (0 lines).

SelectAllItems

Selects all items.

SUB SelectAllItems (BYVAL hListView AS HWND)

SelectItem

Selects a ListView item.

SUB SelectItem (BYVAL hListView AS HWND, BYVAL iIndex AS LONG)

Remarks

Windows does not provide a separate message or function to set the current selection in a listview. Instead, it defines item states or LVIS_* values that determine the listview item’s appearance and functionality. LVIS_FOCUSED and LVIS_SELECTED in particular are the states that determine a listview item’s selection state. Note that the last parameter passed to this method is a mask specifying which bits are about to change. LVIS_FOCUSED and LVIS_SELECTED are defined in commctrl.inc as &H0001 and &H0002 respectively, so you need to set the last four bits of the mask.

SetBkColor

Sets the background color of a list-view control.

FUNCTION SetBkColor (BYVAL hListView AS HWND, BYVAL clrBk AS COLORREF) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

SetBkImage

Sets the background image in a list-view control.

FUNCTION SetBkImage (BYVAL hListView AS HWND, BYVAL pvbki AS LVBKIMAGE PTR) AS BOOLEAN
FUNCTION SetBkImage (BYVAL hListView AS HWND, BYREF vbki AS LVBKIMAGE) AS BOOLEAN

Return value

Returns nonzero if successful, or zero otherwise. Returns zero if the ulFlags member of the LVBKIMAGE structure is LVBKIF_SOURCE_NONE.

Remarks

Because the list-view control uses OLE COM to manipulate the background images, the calling application must call CoInitialize or OleInitialize before using this method. It is best to call one of these functions when the application is initialized and call either CoUninitialize or OleUninitialize when the application is terminating.

SetCallbackMask

Changes the callback mask for a list-view control.

FUNCTION SetCallbackMask (BYVAL hListView AS HWND, BYVAL mask AS DWORD) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

The callback mask of a list-view control is a set of bit flags that specify the item states for which the application, rather than the control, stores the current data. The callback mask applies to all of the control’s items, unlike the callback item designation, which applies to a specific item. The callback mask is zero by default, meaning that the list-view control stores all item state information. After creating a list-view control and initializing its items, you can use the SetCallbackMask method or LVM_SETCALLBACKMASK message to change the callback mask. To retrieve the current callback mask, send the LVM_GETCALLBACKMASK message.

For more information about overlay images and state images, see List-View Image Lists.

For more information on list-view callbacks, see Callback Items and the Callback Mask

SetCheckState

Selects or deselects an item in a list-view control.

SUB SetCheckState (BYVAL hListView AS HWND, BYVAL iIndex AS LONG, BYVAL fCheck AS BOOLEAN)

Remarks

This method should only be used for list-view controls with the LVS_EX_CHECKBOXES style.

SetColumn

Sets the attributes of a list-view column.

FUNCTION SetColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYVAL pcol AS LVCOLUMN PTR) AS BOOLEAN
FUNCTION SetColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYREF col AS LVCOLUMN) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

SetColumnOrderArray

Sets the left-to-right order of columns in a list-view control.

SUB SetColumnOrderArray (BYVAL hListView AS HWND, BYVAL iCount AS LONG, BYVAL prgi AS LONG PTR) AS BOOLEAN

SetColumnWidth

Used to change the width of a column in report view or the width of all columns in list-view mode.

FUNCTION SetColumnWidth (BYVAL hListView AS HWND, BYVAL iCol AS LONG, BYVAL cx AS LONG) AS BOOLEAN

SetDarkMode

Sets the listview dark mode.

FUNCTION SetDarkMode (BYVAL hListView AS HWND) AS HRESULT

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

SetExtendedListViewStyle

Sets extended styles for list-view controls.

SUB SetExtendedListViewStyle (BYVAL hListView AS HWND, BYVAL dwExStyle AS DWORD)

Remarks

For backward compatibility reasons, the SetExtendedListViewStyle method has not been updated to use dwExMask. To use the dwExMask value, use the SetExtendedListViewStyleEx method.

When you use this method to set the LVS_EX_CHECKBOXES style, any previously set state image index will be discarded. All check boxes will be initialized to the unchecked state. The state image index is contained in bits 12 through 15 of the state member of the LVITEMW structure.

SetExtendedListViewStyleEx

Sets extended styles for list-view controls using the style mask.

SUB SetExtendedListViewStyleEx (BYVAL hListView AS HWND, BYVAL dwExMask AS DWORD, BYVAL dwExStyle AS DWORD)

SetGroupHeaderImageList

Assigns an image list to the group header of a list-view control.

FUNCTION SetGroupHeaderImageList (BYVAL hListView AS HWND, BYVAL himl AS HIMAGELIST) AS HIMAGELIST

Return value

Returns the handle to the group header image list previously associated with the control if successful, or NULL otherwise.

Remarks

The current image list will be destroyed when the list-view control is destroyed unless the LVS_SHAREIMAGELISTS style is set. If you use this message to replace one image list with another, your application must explicitly destroy all image lists other than the current one.

SetGroupInfo

Sets group information.

FUNCTION SetGroupInfo (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYVAL pgrp AS LVGROUP PTR) AS LONG
FUNCTION SetGroupInfo (BYVAL hListView AS HWND, BYVAL iGroupId AS LONG, BYREF grp AS LVGROUP) AS LONG

Return value

Returns the index of the group if successful, or -1 otherwise.

Remarks

To use SetGroupInfo, specify Comctl32.dll version 6 in the manifest.

SetGroupMetrics

Sets information about the display of groups.

SUB SetGroupMetrics (BYVAL hListView AS HWND, BYVAL pGroupMetrics AS LVGROUPMETRICS PTR)
SUB SetGroupMetrics (BYVAL hListView AS HWND, BYREF GroupMetrics AS LVGROUPMETRICS)

Remarks

To use SetGroupInfo, specify Comctl32.dll version 6 in the manifest.

SetGroupState

Sets the state for a specified group.

FUNCTION SetGroupState (BYVAL hListView AS HWND, BYVAL dwGroupId AS UINT, _
   BYVAL dwMask AS UINT, BYVAL dwState AS UINT) AS LONG

Return value

Returns the ID of the group (iGroupId) if successful, or -1 otherwise.

Remarks

To use SetGroupState, specify Comctl32.dll version 6 in the manifest.

SetHeaderFont

Sets the font used by the listview header.

FUNCTION ModifyHeaderFont (BYVAL hListView AS HWND, BYREF wszFaceName AS WSTRING, _
   BYVAL lPointSize AS LONG, BYVAL lWeight AS LONG, BYVAL bItalic AS BYTE, BYVAL bUnderline AS BYTE, _
   BYVAL bStrikeOut AS BYTE, BYVAL bCharSet AS BYTE) AS HFONT              

Return value

The handle of the new font. The returned font must be destroyed with DeleteObject when no longer needed to prevent memory leaks.

SetHotCursor

Sets the HCURSOR that the list-view control uses when the pointer is over an item while hot tracking is enabled. To check whether hot tracking is enabled, call SystemParametersInfo.

FUNCTION SetHotCursor (BYVAL hListView AS HWND, BYVAL hCur AS HCURSOR) AS HCURSOR

Return value

Returns an HCURSOR value that is the cursor that was previously used when the pointer was over an item.

Remarks

A list-view control uses hot tracking and hover selection when the LVS_EX_TRACKSELECT style is set.

SetHotItem

Sets the hot item in a list-view control.

FUNCTION SetHotItem (BYVAL hListView AS HWND, BYVAL iIndex AS DWORD) AS LONG

Return value

Returns the index of the item that was previously hot.

SetHoverTime

Sets the amount of time that the mouse cursor must hover over an item before it is selected.

SUB SetHoverTime (BYVAL hListView AS HWND, BYVAL dwHoverTimeMs AS DWORD)

Remarks

The hover time only affects list-view controls that have the LVS_EX_TRACKSELECT, LVS_EX_ONECLICKACTIVATE, or LVS_EX_TWOCLICKACTIVATE extended list-view style.

SetIconSpacing

Sets the spacing between icons in list-view controls set to the LVS_ICON style.

FUNCTION SetIconSpacing (BYVAL hListView AS HWND, BYVAL cx AS SHORT, BYVAL cy AS SHORT) AS DWORD

Return value

Returns a DWORD value that contains the previous x-axis distance in the low word, and the previous y-axis distance in the high word.

Remarks

The cx and cy parameters are relative to the upper-left corner of an icon bitmap. Therefore, to set spacing between icons that do not overlap, the cx or cy values must include the size of the icon, plus the amount of empty space desired between icons. Values that do not include the width of the icon will result in overlaps.

When defining the icon spacing, cx and cy must set to 4 or larger. Smaller values will not yield the desired layout. You can reset cx and cy to the default spacing by setting both values to -1. This approach only allows you to reset both default settings. You cannot reset only cx or cy to the default setting by setting one of them to -1.

SetImageList

Assigns an image list to a list-view control.

FUNCTION SetImageList (BYVAL hListView AS HWND, BYVAL himl AS HIMAGELIST, _
   BYVAL nImageList AS LONG) AS HIMAGELIST

Return value

Returns the handle to the image list previously associated with the control if successful, or NULL otherwise.

Remarks

The current image list will be destroyed when the list-view control is destroyed unless the LVS_SHAREIMAGELISTS style is set. If you use this message to replace one image list with another, your application must explicitly destroy all image lists other than the current one.

SetInfoTip

Sets tooltip text.

FUNCTION SetInfoTip (BYVAL hListView AS HWND, BYVAL plvInfoTip AS LVSETINFOTIP PTR) AS BOOLEAN
FUNCTION SetInfoTip (BYVAL hListView AS HWND, BYREF lvInfoTip AS LVSETINFOTIP) AS BOOLEAN

Return value

Returns TRUE if the tooltip text is set successfully, or FALSE otherwise.

Remarks

To use SetInfoTip, specify Comctl32.dll version 6 in the manifest.

SetInsertMark

Sets the insertion point to the defined position.

FUNCTION SetInsertMark (BYVAL hListView AS HWND, BYVAL plvim AS LVINSERTMARK PTR) AS BOOLEAN
FUNCTION SetInsertMark (BYVAL hListView AS HWND, BYREF lvim AS LVINSERTMARK) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise. Returns FALSE if the size of the LVINSERTMARK structure’s cbSize member does not equal the actual size of the structure, or when an insertion point does not apply in the current view.

Remarks

To use SetInsertMark, specify Comctl32.dll version 6 in the manifest.

SetInsertMarkColor

Sets the color of the insertion point.

FUNCTION SetInsertMarkColor (BYVAL hListView AS HWND, BYVAL clr AS COLORREF) AS COLORREF

Return value

Returns a COLORREF structure set to the previous color.

Remarks

To use SetInsertMarkColor, specify Comctl32.dll version 6 in the manifest.

SetItem

Sets some or all of a list-view item’s attributes.

FUNCTION SetItem (BYVAL hListView AS HWND, BYVAL pitem AS LVITEMW PTR) AS BOOLEAN
FUNCTION SetItem (BYVAL hListView AS HWND, BYREF item AS LVITEMW) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

To set the attributes of a list-view item, set the iItem member of the LVITEM” structure to the index of the item, and set the iSubItem member to zero. For an item, you can use the state, pszText, iImage, and lParam members of the LVITEMW structure to modify these item parameters.

To set the text of a subitem, set the iItem and iSubItem members to indicate the specific subitem, and use the pszText member to specify the text. Alternatively, you can use the SetItemText method to set the text of a subitem. You cannot set the state or lParam members for subitems because subitems do not have these attributes. In version 4.70 and later, you can set the iImage member for subitems. The subitem image will be displayed if the list-view control has the LVS_EX_SUBITEMIMAGES extended style. Previous versions will ignore the subitem image.

SetItemCount

Causes the list-view control to allocate memory for the specified number of items.

FUNCTION SetItemCount (BYVAL hListView AS HWND, BYVAL cItems AS LONG) AS LRESULT

Return value

Returns nonzero if successful, or zero otherwise.

Remarks

If the list-view control was created without the LVS_OWNERDATA style, this method causes the control to allocate its internal data structures for the specified number of items. This prevents the control from having to allocate the data structures every time an item is added.

If the list-view control was created with the LVS_OWNERDATA style (a virtual list view), the SetItemCountEx method should be used.

SetItemCountEx

Sets the virtual number of items in a virtual list view.

FUNCTION SetItemCountEx (BYVAL hListView AS HWND, BYVAL cItems AS LONG, BYVAL dwFlags AS LONG) AS LRESULT

Return value

Returns nonzero if successful, or zero otherwise.

Remarks

This method is intended only for list-view controls that use the LVS_OWNERDATA and LVS_REPORT or LVS_LIST styles.

If the list-view control was created with the LVS_OWNERDATA style, this method sets the virtual number of items that the control contains.

If the list-view control was created without the LVS_OWNERDATA style, the SetItemCount method should be used.

SetItemIndexState

Sets the state of a specified list-view item.

FUNCTION SetItemIndexState (BYVAL hListView AS HWND, BYVAL plvii AS LVITEMINDEX PTR, _
   BYVAL dwData AS UINT, BYVAL mask AS UINT) AS HRESULT
FUNCTION SetItemIndexState (BYVAL hListView AS HWND, BYREF lvii AS LVITEMINDEX, _
   BYVAL dwData AS UINT, BYVAL mask AS UINT) AS HRESULT

Return value

Returns one of the following values of type HRESULT.

SetItemPosition

Moves an item to a specified position in a list-view control (in icon or small icon view).

FUNCTION SetItemPosition (BYVAL hListView AS HWND, BYVAL i AS LONG, _
   BYVAL x AS SHORT, BYVAL y AS SHORT) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the list-view control has the LVS_AUTOARRANGE style, the list-view control is arranged after the position of the item is set.

On Windows Vista, calling this method on a list-view control with the LVS_AUTOARRANGE style does nothing, and the return value is FALSE.

SetItemPosition32

Moves an item to a specified position in a list-view control (in icon or small icon view). This method differs from the SetItemPosition method in that it uses 32-bit coordinates.

SUB SetItemPosition32 (BYVAL hListView AS HWND, BYVAL i AS LONG, _
   BYVAL x AS LONG, BYVAL y AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

If the list-view control has the LVS_AUTOARRANGE style, the list-view control is arranged after the position of the item is set.

On Windows Vista, calling this method on a list-view control with the LVS_AUTOARRANGE style does nothing, and the return value is FALSE.

SetItemState

Changes the state of an item in a list-view control.

SUB SetItemState (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL dwState AS DWORD, BYVAL mask AS DWORD)

Bits of the data parameter that you want to set or clear. You can use SetItemState both to set and to clear bits. To set an item’s overlay image index, set the LVIS_OVERLAYMASK bits. To set an item’s state image index, set the LVIS_STATEIMAGEMASK bits.

Remarks

An item’s state value includes a set of bit flags that indicate the item’s state. The state value can also include image list indexes that indicate the item’s state image and overlay image.

The mask parameter specifies the state bits you want to modify, and the data parameter specifies the new value for those bits. To set a bit in the item’s internal state, set it in both the mask and data parameters. To clear a bit in the item’s internal state, set it in the mask parameter and clear it in the data parameter. To leave a bit unchanged in the item’s internal state, clear it in the mask parameter.

Bits 8 through 11 of the data parameter specify the one-based index of an overlay image in the control’s image lists. Both the full-sized icon image list and the small icon image list can have overlay images. The overlay image is superimposed over the item’s icon image. If these bits are zero, the item has no overlay image. To isolate these bits, use the LVIS_OVERLAYMASK mask. To specify an overlay index, use the INDEXTOOVERLAYMASK macro.

Bits 12 through 15 of the data parameter specify the one-based index of an image in the control’s state image list. The state image is displayed next to an item’s icon to indicate an application-defined state. If these bits are zero, the item has no state image. To isolate these bits, use the LVIS_STATEIMAGEMASK mask. To specify a state image index, use the INDEXTOSTATEIMAGEMASK macro.

SetItemText

Changes the text of a list-view item or subitem.

SUB SetItemText (BYVAL hListView AS HWND, BYVAL i AS LONG, BYVAL iSubItem AS LONG, BYVAL pwszText AS WSTRING)
FUNCTION SetText (BYVAL hListView AS HWND, BYVAL i AS LONG, BYREF wszText AS WSTRING)

SetOutlineColor

Sets the color of the border of a list-view control if the LVS_EX_BORDERSELECT extended window style is set.

FUNCTION SetOutlineColor (BYVAL hListView AS HWND, BYVAL clr AS COLORREF) AS COLORREF

Return value

Returns a COLORREF structure that contains the outline color.

Remarks

To use SetOutlineColor, specify Comctl32.dll version 6 in the manifest.

SetSelectedColumn

Sets the index of the selected column.

SUB SetSelectedColumn (BYVAL hListView AS HWND, BYVAL iCol AS LONG)

Remarks

To use SetSelectedColumn, specify Comctl32.dll version 6 in the manifest.

SetSelectionMark

Sets the selection mark in a list-view control.

FUNCTION SetSelectionMark (BYVAL hListView AS HWND, BYVAL iIndex AS LONG) AS LONG

Return value

Returns the previous selection mark, or -1 if there is no previous selection mark.

Remarks

The selection mark is the item index from which a multiple selection starts. This macro does not affect the selection state of the item.

SetTextBkColor

Sets the background color of text in a list-view control.

FUNCTION SetTextBkColor (BYVAL hListView AS HWND, BYVAL clrTextBk AS COLORREF) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

SetTextColor

Sets the text color of a list-view control.

FUNCTION SetTextColor (BYVAL hListView AS HWND, BYVAL clrText AS COLORREF) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

SetTileInfo

Sets information for an existing tile of a list-view control.

FUNCTION SetTileInfo (BYVAL hListView AS HWND, BYVAL plvtinfo AS LVTILEINFO PTR) AS BOOLEAN
FUNCTION SetTileInfo (BYVAL hListView AS HWND, BYREF lvtinfo AS LVTILEINFO) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

To use SetTileInfo, specify Comctl32.dll version 6 in the manifest.

SetTileViewInfo

Sets information that a list-view control uses in tile view.

FUNCTION SetTileViewInfo (BYVAL hListView AS HWND, BYVAL plvtvinfo AS LVTILEVIEWINFO PTR) AS BOOLEAN
FUNCTION SetTileViewInfo (BYVAL hListView AS HWND, BYREF lvtvinfo AS LVTILEVIEWINFO) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

To use SetTileViewInfo, specify Comctl32.dll version 6 in the manifest.

SetToolTips

Sets the tooltip control that the list-view control will use to display tooltips.

FUNCTION SetToolTips (BYVAL hListView AS HWND, BYVAL hwndToolTip AS HWND) AS HWND

Return value

Returns the handle to the previous tooltip control.

SetTooltipsFont

Sets the tooltip control that the list-view control will use to display tooltips.

SUB SetTooltipsFont (BYVAL hListView AS HWND, BYVAL hFont AS HFONT = NULL, BYVAL fRedraw AS BOOLEAN = FALSE)

Return value

Returns the handle to the previous tooltip control.

SetView

Sets the view of a list-view control.

FUNCTION SetView (BYVAL hListView AS HWND, BYVAL iView AS DWORD) AS LONG

Return value

Returns 1 if successful, or UINT_MAX otherwise. For example, returns UINT_MAX if the view is invalid.

Remarks

To use SetView, specify Comctl32.dll version 6 in the manifest.

SetWorkAreas

Sets the working areas within a list-view control.

SUB SetWorkAreas (BYVAL hListView AS HWND, BYVAL nWorkAreas AS LONG, BYVAL prc AS RECT PTR)
SUB SetWorkAreas (BYVAL hListView AS HWND, BYVAL nWorkAreas AS LONG, BYREF rc AS RECT)

SortGroups

Uses an application-defined comparison function to sort groups by ID within a list-view control.

FUNCTION SortGroups (BYVAL hListView AS HWND, BYVAL _pfnGroupCompare AS PFNLVGROUPCOMPARE PTR, _
   BYVAL _plv AS ANY PTR) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

To use SortGroups, specify Comctl32.dll version 6 in the manifest.

SortItems

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence.

FUNCTION SortItems (BYVAL hListView AS HWND, BYVAL _pfnCompare AS PFNLVCOMPARE PTR, _
   BYVAL _lPrm AS LPARAM) AS LONG

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

The comparison function has the following form.

FUNCTION CompareFunc(BYVAL lParam1 AS LPARAM, BYVAL lParam2 AS LPARAM, BYVAL _lPrm AS LPARAM) AS LONG

The lParam1 parameter is the value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items’ LVITEMW structure when they were inserted into the list. The *_lPrm* parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

SortItemsEx

Uses an application-defined comparison function to sort the items of a list-view control. The index of each item changes to reflect the new sequence.

FUNCTION SortItemsEx (BYVAL hListView AS HWND, BYVAL _pfnCompare AS PFNLVCOMPARE PTR, _
   BYVAL _lPrm AS LPARAM) AS LONG

Return value

Returns TRUE if successful, or FALSE otherwise.

Remarks

The comparison function has the following form.

FUNCTION CompareFunc(BYVAL lParam1 AS LPARAM, BYVAL lParam2 AS LPARAM, BYVAL _lPrm AS LPARAM) AS LONG

The lParam1 parameter is the value associated with the first item being compared; and the lParam2 parameter is the value associated with the second item. These are the values that were specified in the lParam member of the items’ LVITEMW structure when they were inserted into the list. The *_lPrm* parameter is the same value passed to the LVM_SORTITEMS message.

The comparison function must return a negative value if the first item should precede the second, a positive value if the first item should follow the second, or zero if the two items are equivalent.

This metod is similar to SortItems, except for the type of information passed to the comparison function. With SortItemsEx, the item’s index is passed instead of its lparam value.

Note: During the sorting process, the list-view contents are unstable. If the callback function sends any messages to the list-view control aside from LVM_GETITEM (GetItem), the results are unpredictable.

SubItemHitTest

Determines which list-view item or subitem is located at a given position.

FUNCTION SubItemHitTest (BYVAL hListView AS HWND, BYVAL plvhti AS LVHITTESTINFO PTR) AS LONG
FUNCTION SubItemHitTest (BYVAL hListView AS HWND, BYREF lvhti AS LVHITTESTINFO) AS LONG

Return value

Returns the index of the item or subitem tested, if any, or -1 otherwise. If an item or subitem is at the given coordinates, the fields of the LVHITTESTINFO structure will be filled with the applicable hit information.

SubItemHitTestEx

Determines which list-view item or subitem is located at a given position.

FUNCTION SubItemHitTestEx (BYVAL hListView AS HWND, BYVAL plvhti AS LVHITTESTINFO PTR) AS LONG
FUNCTION SubItemHitTestEx (BYVAL hListView AS HWND, BYREF lvhti AS LVHITTESTINFO) AS LONG

Return value

Returns the index of the item or subitem tested, if any, or -1 otherwise. If an item or subitem is at the given coordinates, the fields of the LVHITTESTINFO structure will be filled with the applicable hit information.

Remarks

This macro passes -1 as the wparam of the message, specifying that the iGroup member of plvhti is retrieved.

UnselectAllItems

Unselects all items.

SUB UnselectAllItems (BYVAL hListView AS HWND)

UnselectItem

Unselects an item in a ListView.

SUB UnselectItem (BYVAL hListView AS HWND, BYVAL iIndex AS LONG)

Update

Updates a list-view item. If the list-view control has the LVS_AUTOARRANGE style, this method causes the list-view control to be arranged.

FUNCTION Update (BYVAL hListView AS HWND, BYVAL iItem AS LONG) AS BOOLEAN

Return value

Returns TRUE if successful, or FALSE otherwise.